/**
 * @file ts.h
 * @brief 触摸屏输入处理模块的头文件
 * @details 定义了用于表示坐标的数据结构，并声明了用于从触摸屏设备
 * 读取坐标的函数接口。
 * @version 1.0
 * @date 2025-07-07
 */

// 标准的 "Include Guard"，防止此头文件在同一个编译单元中被多次包含
#ifndef TS_H
#define TS_H
#include <linux/input.h>

/**
 * @struct postion
 * @brief 定义了一个用于存储二维坐标的结构体。
 * @details 简单地包含了 x 和 y 两个整型成员，分别代表水平和垂直坐标。
 */
struct postion
{
    int x; // X轴坐标
    int y; // Y轴坐标
};

/**
 * @brief (公共接口) 阻塞式地获取一个触摸屏坐标。
 * @details 这是推荐使用的、简化的接口。函数会持续从设备读取数据，直到一个
 * 完整的(X, Y)坐标被成功解析。在获取到坐标之前，程序会一直阻塞在此函数。
 * @param fd 已打开的触摸屏设备的文件描述符 (例如 /dev/input/eventX)。
 * @return struct postion 返回一个包含x和y坐标的结构体。
 * @retval postion.x, postion.y 成功获取到的坐标值。
 * @retval {-1, -1} 如果发生读取错误或传入无效的fd，返回x和y均为-1的结构体。
 */
struct postion ts_xy(int fd);

/**
 * @brief (高级接口) 非阻塞地尝试读取并解析一个触摸事件。
 * @details 这是一个底层的、非阻塞的状态机函数。每次调用它只会尝试读取一个
 * 输入事件。调用者需要在一个循环中持续调用此函数来处理事件流。
 * @param fd 已打开的触摸屏设备的文件描述符。
 * @param[out] pos_out 一个指向 struct postion 的指针。如果函数成功解析出
 * 一个完整坐标，该坐标值将被写入此指针指向的内存中。
 * @return int 函数的返回值表示当前的状态：
 * @retval 1  表示成功获取到一个完整的(X, Y)坐标，该坐标已存入 pos_out。
 * @retval 0  表示只收到了部分数据（例如，只收到了X或Y），或者收到的不是坐标事件。
 * 需要继续调用此函数来获取下一个事件。
 * @retval -1 表示从设备读取数据时发生错误。
 */
int get_touch_event(int fd, struct postion *pos_out);

#endif //_TS_H_